<html>
<head><title>The st package</title></head>
<body>

<h1>The st package</h1>
<h2>Symbol table package.</h2>
<h3></h3>
<hr>
<ul>
<li><a href="stExtAbs.html"><h3>External abstracts</h3></a>
<li><a href="stAllAbs.html"><h3>All abstracts</h3></a>
<li><a href="stExtDet.html#prototypes"><h3>External functions</h3></a>
<li><a href="stAllDet.html#prototypes"><h3>All functions</h3></a>
</ul>

<hr>

<a name="description">
The st library provides functions to create, maintain,
  and query symbol tables.
</a>

<hr>
<!-- Function Prototypes and description -->

<dl>
<a name="prototypes"></a>
<dt><pre>
int <i></i>
<a name="st_add_direct"><b>st_add_direct</b></a>(
  st_table * <b>table</b>, <i></i>
  void * <b>key</b>, <i></i>
  void * <b>value</b> <i></i>
)
</pre>
<dd> Place 'value' in 'table' under the key 'key'. This is done without checking if 'key' is in 'table' already. This should only be used if you are sure there is not already an entry for 'key', since it is undefined which entry you would later get from st_lookup or st_find_or_add. Returns 1 if successful; ST_OUT_OF_MEM otherwise.
<p>

<dd> <b>Side Effects</b> None
<p>

<dt><pre>
st_table * <i></i>
<a name="st_copy"><b>st_copy</b></a>(
  st_table * <b>old_table</b> <i></i>
)
</pre>
<dd> Return a copy of old_table and all its members. (st_table *) 0 is returned if there was insufficient memory to do the copy.
<p>

<dd> <b>Side Effects</b> None
<p>

<dt><pre>
 <i></i>
<a name="st_count"><b>st_count</b></a>(
   <b>table</b> <i></i>
)
</pre>
<dd> Returns the number of entries in the table `table'.
<p>

<dd> <b>Side Effects</b> None
<p>

<dt><pre>
int <i></i>
<a name="st_delete_int"><b>st_delete_int</b></a>(
  st_table * <b>table</b>, <i></i>
  void * <b>keyp</b>, <i></i>
  int * <b>value</b> <i></i>
)
</pre>
<dd> Delete the entry with the key pointed to by `keyp'. `value' must be a pointer to an integer. If the entry is found, 1 is returned, the variable pointed by `keyp' is set to the actual key and the variable pointed by `value' is set to the corresponding entry. (This allows the freeing of the associated storage.) If the entry is not found, then 0 is returned and nothing is changed.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_delete">st_delete</a>
</code>

<dt><pre>
int <i></i>
<a name="st_delete"><b>st_delete</b></a>(
  st_table * <b>table</b>, <i></i>
  void * <b>keyp</b>, <i></i>
  void * <b>value</b> <i></i>
)
</pre>
<dd> Delete the entry with the key pointed to by `keyp'. If the entry is found, 1 is returned, the variable pointed by `keyp' is set to the actual key and the variable pointed by `value' is set to the corresponding entry. (This allows the freeing of the associated storage.) If the entry is not found, then 0 is returned and nothing is changed.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_delete_int">st_delete_int</a>
</code>

<dt><pre>
int <i></i>
<a name="st_find_or_add"><b>st_find_or_add</b></a>(
  st_table * <b>table</b>, <i></i>
  void * <b>key</b>, <i></i>
  void * <b>slot</b> <i></i>
)
</pre>
<dd> Lookup `key' in `table'. If not found, create an entry. In either case set slot to point to the field in the entry where the value is stored. The value associated with `key' may then be changed by accessing directly through slot. Returns 1 if an entry already existed, 0 if it did not exist and creation was successful; ST_OUT_OF_MEM otherwise. As an example: <pre> char **slot; </pre> <pre> char *key; </pre> <pre> char *value = (char *) item_ptr <-- ptr to a malloc'd structure </pre> <pre> if (st_find_or_add(table, key, &slot) == 1) { </pre> <pre> FREE(*slot); <-- free the old value of the record </pre> <pre> } </pre> <pre> *slot = value; <-- attach the new value to the record </pre> This replaces the equivelent code: <pre> if (st_lookup(table, key, &ovalue) == 1) { </pre> <pre> FREE(ovalue); </pre> <pre> } </pre> <pre> st_insert(table, key, value); </pre>
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_find">st_find</a>
</code>

<dt><pre>
int <i></i>
<a name="st_find"><b>st_find</b></a>(
  st_table * <b>table</b>, <i></i>
  void * <b>key</b>, <i></i>
  void * <b>slot</b> <i></i>
)
</pre>
<dd> Like st_find_or_add, but does not create an entry if one is not found.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_find_or_add">st_find_or_add</a>
</code>

<dt><pre>
 <i></i>
<a name="st_foreach_item_int"><b>st_foreach_item_int</b></a>(
   <b>table</b>, <i></i>
   <b>gen</b>, <i></i>
   <b>key</b>, <i></i>
   <b>value</b> <i></i>
)
</pre>
<dd> An iteration macro which loops over all the entries in `table', setting `key' to point to the key and `value' to the associated value (if it is not nil). `value' is assumed to be a pointer to an integer. `gen' is a generator variable used internally. Sample usage: <pre> char *key; </pre> <pre> int value; </pre> <pre> st_generator *gen; </pre> <pre> st_foreach_item_int(table, gen, &key, &value) { </pre> <pre> process_item(value); </pre> <pre> } </pre>
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_foreach_item">st_foreach_item</a>
<a href="stAllDet.html#st_foreach">st_foreach</a>
</code>

<dt><pre>
 <i></i>
<a name="st_foreach_item"><b>st_foreach_item</b></a>(
   <b>table</b>, <i></i>
   <b>gen</b>, <i></i>
   <b>key</b>, <i></i>
   <b>value</b> <i></i>
)
</pre>
<dd> An iteration macro which loops over all the entries in `table', setting `key' to point to the key and `value' to the associated value (if it is not nil). `gen' is a generator variable used internally. Sample usage: <pre> char *key, *value; </pre> <pre> st_generator *gen; </pre> <pre> st_foreach_item(table, gen, &key, &value) { </pre> <pre> process_item(value); </pre> <pre> } </pre>
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_foreach_item_int">st_foreach_item_int</a>
<a href="stAllDet.html#st_foreach">st_foreach</a>
</code>

<dt><pre>
int <i></i>
<a name="st_foreach"><b>st_foreach</b></a>(
  st_table * <b>table</b>, <i></i>
  ST_PFSR  <b>func</b>, <i></i>
  char * <b>arg</b> <i></i>
)
</pre>
<dd> For each (key, value) record in `table', st_foreach call func with the arguments <pre> (*func)(key, value, arg) </pre> If func returns ST_CONTINUE, st_foreach continues processing entries. If func returns ST_STOP, st_foreach stops processing and returns immediately. If func returns ST_DELETE, then the entry is deleted from the symbol table and st_foreach continues. In the case of ST_DELETE, it is func's responsibility to free the key and value, if necessary.<p> The routine returns 1 if all items in the table were generated and 0 if the generation sequence was aborted using ST_STOP. The order in which the records are visited will be seemingly random.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_foreach_item">st_foreach_item</a>
<a href="stAllDet.html#st_foreach_item_int">st_foreach_item_int</a>
</code>

<dt><pre>
void <i></i>
<a name="st_free_gen"><b>st_free_gen</b></a>(
  st_generator * <b>gen</b> <i></i>
)
</pre>
<dd> After generating all items in a generation sequence, this routine must be called to reclaim the resources associated with `gen'.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_init_gen">st_init_gen</a>
</code>

<dt><pre>
void <i></i>
<a name="st_free_table"><b>st_free_table</b></a>(
  st_table * <b>table</b> <i></i>
)
</pre>
<dd> Any internal storage associated with table is freed. It is the user's responsibility to free any storage associated with the pointers he placed in the table (by perhaps using st_foreach).
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_init_table">st_init_table</a>
<a href="stAllDet.html#st_init_table_with_params">st_init_table_with_params</a>
</code>

<dt><pre>
int <i></i>
<a name="st_gen_int"><b>st_gen_int</b></a>(
  st_generator * <b>gen</b>, <i></i>
  void * <b>key_p</b>, <i></i>
  int * <b>value_p</b> <i></i>
)
</pre>
<dd> Given a generator returned by st_init_gen(), this routine returns the next (key, value) pair in the generation sequence. `value_p' must be a pointer to an integer. The pointer `value_p' can be zero which means no value will be returned. When there are no more items in the generation sequence, the routine returns 0.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_gen">st_gen</a>
</code>

<dt><pre>
int <i></i>
<a name="st_gen"><b>st_gen</b></a>(
  st_generator * <b>gen</b>, <i></i>
  void * <b>key_p</b>, <i></i>
  void * <b>value_p</b> <i></i>
)
</pre>
<dd> Given a generator returned by st_init_gen(), this routine returns the next (key, value) pair in the generation sequence. The pointer `value_p' can be zero which means no value will be returned. When there are no more items in the generation sequence, the routine returns 0. While using a generation sequence, deleting any (key, value) pair other than the one just generated may cause a fatal error when st_gen() is called later in the sequence and is therefore not recommended.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_gen_int">st_gen_int</a>
</code>

<dt><pre>
st_generator * <i></i>
<a name="st_init_gen"><b>st_init_gen</b></a>(
  st_table * <b>table</b> <i></i>
)
</pre>
<dd> Returns a generator handle which when used with st_gen() will progressively return each (key, value) record in `table'.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_free_gen">st_free_gen</a>
</code>

<dt><pre>
st_table * <i></i>
<a name="st_init_table_with_params"><b>st_init_table_with_params</b></a>(
  ST_PFICPCP  <b>compare</b>, <i></i>
  ST_PFICPI  <b>hash</b>, <i></i>
  int  <b>size</b>, <i></i>
  int  <b>density</b>, <i></i>
  double  <b>grow_factor</b>, <i></i>
  int  <b>reorder_flag</b> <i></i>
)
</pre>
<dd> The full blown table initializer. compare and hash are the same as in st_init_table. density is the largest the average number of entries per hash bin there should be before the table is grown. grow_factor is the factor the table is grown by when it becomes too full. size is the initial number of bins to be allocated for the hash table. If reorder_flag is non-zero, then every time an entry is found, it is moved to the top of the chain.<p> st_init_table(compare, hash) is equivelent to <pre> st_init_table_with_params(compare, hash, ST_DEFAULT_INIT_TABLE_SIZE, ST_DEFAULT_MAX_DENSITY, ST_DEFAULT_GROW_FACTOR, ST_DEFAULT_REORDER_FLAG); </pre>
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_init_table">st_init_table</a>
<a href="stAllDet.html#st_free_table">st_free_table</a>
</code>

<dt><pre>
st_table * <i></i>
<a name="st_init_table"><b>st_init_table</b></a>(
  ST_PFICPCP  <b>compare</b>, <i></i>
  ST_PFICPI  <b>hash</b> <i></i>
)
</pre>
<dd> Create and initialize a table with the comparison function compare_fn and hash function hash_fn. compare_fn is <pre> int compare_fn(const char *key1, const char *key2) </pre> It returns <,=,> 0 depending on whether key1 <,=,> key2 by some measure.<p> hash_fn is <pre> int hash_fn(char *key, int modulus) </pre> It returns a integer between 0 and modulus-1 such that if compare_fn(key1,key2) == 0 then hash_fn(key1) == hash_fn(key2).<p> There are five predefined hash and comparison functions in st. For keys as numbers: <pre> st_numhash(key, modulus) { return (unsigned int) key % modulus; } </pre> <pre> st_numcmp(x,y) { return (int) x - (int) y; } </pre> For keys as pointers: <pre> st_ptrhash(key, modulus) { return ((unsigned int) key/4) % modulus } </pre> <pre> st_ptrcmp(x,y) { return (int) x - (int) y; } </pre> For keys as strings: <pre> st_strhash(x,y) - a reasonable hashing function for strings </pre> <pre> strcmp(x,y) - the standard library function </pre> It is recommended to use these particular functions if they fit your needs, since st will recognize certain of them and run more quickly because of it.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_init_table_with_params">st_init_table_with_params</a>
<a href="stAllDet.html#st_free_table">st_free_table</a>
</code>

<dt><pre>
int <i></i>
<a name="st_insert"><b>st_insert</b></a>(
  st_table * <b>table</b>, <i></i>
  void * <b>key</b>, <i></i>
  void * <b>value</b> <i></i>
)
</pre>
<dd> Insert value in table under the key 'key'. Returns 1 if there was an entry already under the key; 0 if there was no entry under the key and insertion was successful; ST_OUT_OF_MEM otherwise. In either of the first two cases the new value is added.
<p>

<dd> <b>Side Effects</b> None
<p>

<dt><pre>
 <i></i>
<a name="st_is_member"><b>st_is_member</b></a>(
   <b>table</b>, <i></i>
   <b>key</b> <i></i>
)
</pre>
<dd> Returns 1 if there is an entry under `key' in `table', 0 otherwise.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_lookup">st_lookup</a>
</code>

<dt><pre>
int <i></i>
<a name="st_lookup_int"><b>st_lookup_int</b></a>(
  st_table * <b>table</b>, <i></i>
  void * <b>key</b>, <i></i>
  int * <b>value</b> <i></i>
)
</pre>
<dd> Lookup up `key' in `table'. If an entry is found, 1 is returned and if `value' is not nil, the variable it points to is set to the associated integer value. If an entry is not found, 0 is return and the variable pointed by `value' is unchanged.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_lookup">st_lookup</a>
</code>

<dt><pre>
int <i></i>
<a name="st_lookup"><b>st_lookup</b></a>(
  st_table * <b>table</b>, <i></i>
  void * <b>key</b>, <i></i>
  void * <b>value</b> <i></i>
)
</pre>
<dd> Lookup up `key' in `table'. If an entry is found, 1 is returned and if `value' is not nil, the variable it points to is set to the associated value. If an entry is not found, 0 is returned and the variable pointed by value is unchanged.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_lookup_int">st_lookup_int</a>
</code>

<dt><pre>
int <i></i>
<a name="st_numcmp"><b>st_numcmp</b></a>(
  const char * <b>x</b>, <i></i>
  const char * <b>y</b> <i></i>
)
</pre>
<dd> integer number comparison function.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_init_table">st_init_table</a>
<a href="stAllDet.html#st_numhash">st_numhash</a>
</code>

<dt><pre>
int <i></i>
<a name="st_numhash"><b>st_numhash</b></a>(
  char * <b>x</b>, <i></i>
  int  <b>size</b> <i></i>
)
</pre>
<dd> Integer number hash function.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_init_table">st_init_table</a>
<a href="stAllDet.html#st_numcmp">st_numcmp</a>
</code>

<dt><pre>
int <i></i>
<a name="st_ptrcmp"><b>st_ptrcmp</b></a>(
  const char * <b>x</b>, <i></i>
  const char * <b>y</b> <i></i>
)
</pre>
<dd> Pointer comparison function.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_init_table">st_init_table</a>
<a href="stAllDet.html#st_ptrhash">st_ptrhash</a>
</code>

<dt><pre>
int <i></i>
<a name="st_ptrhash"><b>st_ptrhash</b></a>(
  char * <b>x</b>, <i></i>
  int  <b>size</b> <i></i>
)
</pre>
<dd> Pointer hash function.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_init_table">st_init_table</a>
<a href="stAllDet.html#st_ptrcmp">st_ptrcmp</a>
</code>

<dt><pre>
int <i></i>
<a name="st_strhash"><b>st_strhash</b></a>(
  char * <b>string</b>, <i></i>
  int  <b>modulus</b> <i></i>
)
</pre>
<dd> String hash function.
<p>

<dd> <b>Side Effects</b> None
<p>

<dd> <b>See Also</b> <code><a href="stAllDet.html#st_init_table">st_init_table</a>
</code>


</dl>

<hr>

Generated automatically by <code>extdoc</code> on 20040102

</body></html>
